This PR addresses the incompatibility between HostingStartup and .NET Aspire integrations by providing comprehensive migration guidance from the legacy hosting pattern to the modern IHostApplicationBuilder approach.

The Problem

.NET Aspire integrations require IHostApplicationBuilder, but HostingStartup only provides access to the older IWebHostBuilder. This fundamental API difference means:

• Aspire integration methods like AddNpgsqlDbContext() are not available
• Modern hosting features (service discovery, built-in telemetry, health checks) can't be configured
• Applications using HostingStartup miss out on .NET Aspire's observability and resilience patterns

The Solution

The documentation emphasizes migration as the necessary path forward rather than workarounds, recognizing that HostingStartup represents decade-old technology that predates modern .NET hosting patterns.

Key Content

• Clear explanation of why the incompatibility exists at the API level
• Before/after examples showing the transition from IWebHostBuilder to IHostApplicationBuilder
• Conceptual guidance on the hosting model changes introduced in ASP.NET Core 6.0+
• Migration resources linking to official ASP.NET Core migration guides and David Fowl's migration patterns

Example Migration

Before (HostingStartup - incompatible):

public class MyDatabaseStartup : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) // ❌ Wrong builder type
    {
        builder.ConfigureServices(services => { ... });
    }
}

After (Modern hosting - compatible):

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();                    // ✅ Aspire integration
builder.AddNpgsqlDbContext<MyDbContext>("postgres"); // ✅ Works correctly

This approach guides developers toward modern .NET patterns while ensuring they can leverage .NET Aspire's full feature set including service discovery, telemetry, and resilience capabilities.

Fixes #3861.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Internal previews